home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 15 / CU Amiga Magazine's Super CD-ROM 15 (1997)(EMAP Images)(GB)[!][issue 1997-10].iso / CUCD / Graphics / Ghostscript / source / c-style.txt < prev    next >
Text File  |  1996-11-03  |  7KB  |  224 lines
  1.    Copyright (C) 1996 Aladdin Enterprises.  All rights reserved.
  2.   
  3.   This file is part of Aladdin Ghostscript.
  4.   
  5.   Aladdin Ghostscript is distributed with NO WARRANTY OF ANY KIND.  No author
  6.   or distributor accepts any responsibility for the consequences of using it,
  7.   or for whether it serves any particular purpose or works at all, unless he
  8.   or she says so in writing.  Refer to the Aladdin Ghostscript Free Public
  9.   License (the "License") for full details.
  10.   
  11.   Every copy of Aladdin Ghostscript must include a copy of the License,
  12.   normally in a plain ASCII text file named PUBLIC.  The License grants you
  13.   the right to copy, modify and redistribute Aladdin Ghostscript, but only
  14.   under certain conditions described in the License.  Among other things, the
  15.   License requires that the copyright notice and this notice be preserved on
  16.   all copies.
  17.  
  18. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  19.  
  20. This file, c-style.txt, describes Aladdin's C coding guidelines.
  21.  
  22. For an overview of Ghostscript and a list of the documentation files, see
  23. README.
  24.  
  25. Generalities
  26. ============
  27.  
  28. All the rules below are meant to produce code that is easy to read.  If you
  29. find a rule getting in your way or producing ugly-looking results once in a
  30. while, it's OK to break it.
  31.  
  32. Indentation
  33. -----------
  34.  
  35. Tab stops are set every 8 columns.  However, tabs are not equivalent to
  36. logical nesting levels for C code: see below for details.
  37.  
  38. File layout
  39. -----------
  40.  
  41. Every code file should start with comments containing a copyright notice,
  42. the name of the file, and a half-to-one-line summary of what the file
  43. contains.
  44.  
  45. C code
  46. ======
  47.  
  48. Indentation
  49. -----------
  50.  
  51. Put the first indentation point at the first tab stop; thereafter, each
  52. level of logical nesting indents by an additional 4 columns.  Proceed as
  53. follows:
  54.  
  55.     { ... in-line compound statement ...
  56.       ... (indented +2 columns)
  57.     }
  58.     ... construct requiring subordinate code ...
  59.       ... subordinate simple statement ... (indented +2 columns)
  60.     ... construct requiring subordinate code ...
  61.       { ... subordinate code ...
  62.         ... (indented +4 columns)
  63.       }
  64.  
  65. Or you can do this if you prefer:
  66.  
  67.     {
  68.       ... in-line compound statement ...
  69.     }
  70.     ... construct requiring subordinate code ...
  71.       ... subordinate simple statement ...
  72.     ... construct requiring subordinate code ...
  73.       {
  74.         ... subordinate code ...
  75.       }
  76.  
  77. But not this:
  78.  
  79.     if ... {
  80.       ... subordinate code ...
  81.     } else {
  82.       ... subordinate code ...
  83.     }
  84.  
  85. Spaces
  86. ------
  87.  
  88. Do put a space:
  89.     - after every comma and semicolon, unless it ends a line;
  90.     - around every binary operator, although you can omit the spaces
  91.     around the innermost operator in a nested expression if you like;
  92.     - on both sides of the the parentheses of an if, for, or while.
  93.  
  94. Don't put a space:
  95.     - at the end of a line;
  96.     - before a comma or semicolon;
  97.     - after unary prefix operators;
  98.     - before the parenthesis of a macro or procedure call.
  99.  
  100. Parentheses
  101. -----------
  102.  
  103. There are just a few places where parentheses are important:
  104.  
  105.     - In expressions that mix && and ||, around the inner
  106.     subexpressions, even if not required by precedence, e.g.,
  107.         (xx && yy) || zz
  108.  
  109.     - In expressions that mix &, |, and/or shifts, especially if
  110.     mixing these with other operators, around the inner subexpressions
  111.     similarly, e.g.,
  112.         (x << 3) | (y >> 5)
  113.  
  114.     - In macro definitions, around every use of an argument that
  115.     logically could be an expression, e.g.,
  116.         ((x) * (x) + (y) * (y))
  117.  
  118. Anywhere else, given the choice, use fewer parentheses.
  119.  
  120. As a matter of personal preference, most of the existing Ghostscript code
  121. puts parentheses around conditional expressions, even if they aren't
  122. syntactically required.
  123.  
  124. Types
  125. -----
  126.  
  127. Use 'private' instead of 'static' for constructs (procedures and variables)
  128. declared at the outermost scope.  This allows making such constructs either
  129. visible or invisible to profilers with a single changed #define.
  130.  
  131. Use const wherever possible and appropriate.
  132.  
  133. If you find yourself wanting to use void *, try to find an alternative using
  134. unions or (in the case of super- and subclasses) casts, unless you're
  135. writing something like a memory manager that really treats memory as opaque.
  136.  
  137. Use anonymous structures as little as possible.  Declare structure types
  138. like this (the _t on the type name is preferable but not required):
  139.  
  140.     typedef struct xxx_yyy_s {
  141.       ... members ...
  142.     } xxx_yyy_t;
  143.  
  144. Names
  145. -----
  146.  
  147. Use fully spelled-out English words in names rather than contractions.  This
  148. is most important for procedure and macro names, global variables and
  149. constants, #defined and enum values, structure and other typedef names, and
  150. structure member names, and for argument and variable names which have
  151. uninformative types like int.  It's not very important for arguments or
  152. local variables of distinctive types, or for local index or count variables.
  153.  
  154. Procedures, variables, and structures visible outside a single .c file
  155. should generally have a prefix that indicates what subsystem they belong to
  156. (in the case of Ghostscript, gs_ or gx_).  This rule isn't followed very
  157. consistently.
  158.  
  159. Commenting
  160. ----------
  161.  
  162. The most important descriptive comments are ones in header files that
  163. describe structures, including invariants.  But every procedure or structure
  164. declaration, or group of other declarations, should have a comment.
  165.  
  166. Other
  167. -----
  168.  
  169. Format procedures as follows:
  170.  
  171. scope return_type
  172. proc_name(type1 arg1, type2 arg2, type3 arg3, type4 verylongargument4,
  173.   type5 argument5)
  174. {    ... body ...
  175. }
  176.  
  177. Leave a blank line after the declarations of local variables in a procedure
  178. or compound statement, unless there's only 1 variable and the scope is less
  179. than 10 lines or so.
  180.  
  181. Global variables
  182. ----------------
  183.  
  184. Avoid global variables (non-const data) like the plague.  Avoid global const
  185. data, but don't knock yourself out over it.
  186.  
  187. Local variables
  188. ---------------
  189.  
  190. Avoid assigning new values to procedure parameters.  It makes debugging very
  191. confusing when the parameter values printed for a procedure are not the ones
  192. actually supplied by the caller.
  193.  
  194. If a local variable only gets assigned a value once, assign it that value at
  195. its declaration, if convenient.  E.g.,
  196.  
  197.         int x = <some expression>;
  198.  
  199. rather than
  200.  
  201.         int x;
  202.         ...
  203.         x = <some expression>;
  204.  
  205. Error handling
  206. --------------
  207.  
  208. By convention, nearly all procedures return an int that indicates the
  209. outcome of the call: 0 indicates a normal return, >0 indicates a non-error
  210. return other than the normal case, and <0 indicates an error.  All callers
  211. should check for error returns and, in general, propagate them to *their*
  212. caller.
  213.  
  214. PostScript code
  215. ===============
  216.  
  217. Put indentation points every 3 spaces.
  218.  
  219. Format procedure definitions like this:
  220.  
  221. /procname        % <arg1> <arg2> procname <result1> <result2>
  222.  { ...code...
  223.  } bind def
  224.